Publishing a script ==================== ``rise.publish`` turns a runnable MATLAB script into a typeset PDF. The script stays a script: it runs in the editor exactly as before, and the only convention is on comments, the one the editor's cell mode already uses. .. code-block:: matlab rise.publish('rbc_walkthrough.m') rise.publish('rbc_walkthrough.m', 'Title', 'A first walkthrough') Each ``%%`` title becomes a numbered section. The comment block under it becomes prose. The code becomes a syntax-highlighted listing. Whatever the code printed appears underneath it, and every figure it drew is placed where it was drawn. The point is that the document and the code are one file. Nothing is written twice, so nothing can drift out of agreement with the code that produced it, and the numbers in the document are the ones that run produced on the day it was made. .. contents:: :local: :depth: 2 The markup ----------- Block markup, written in comments: .. list-table:: :header-rows: 1 :widths: 24 76 * - Written - Becomes * - ``%% Title {#name}`` - a numbered section, with an optional label * - ``%%% Title`` - a subsection * - ``%%%% Title`` - a subsubsection * - ``%% ...`` - continues the current section, no new heading * - ``% text`` - prose, if it comes before the first line of code * - ``%`` - a blank line in the prose * - ``% * item`` - a bullet * - ``% # item`` - a numbered item * - ``% | a | b |`` - a row of a table * - ``% $$ ... $$`` - display mathematics * - ``%{ ... %}`` - a block of prose * - ``% ...`` - raw LaTeX, passed through untouched Inline, prose recognises ``` `code` ```, ``$math$``, ``**bold**``, ``*italic*`` and ``_italic_``. Tables ~~~~~~~ A table is written as pipe-delimited rows. A row of dashes marks the header and is not itself printed; it may be omitted, in which case the first row is the header. .. code-block:: matlab % | Parameter | Value | What it governs | % |---|---|---| % | beta | 0.99 | the discount factor | % | alpha | 0.45 | the weight on capital | Cells are plain text. Emphasis inside a cell is not offered, rather than offered and silently broken. Emphasis ~~~~~~~~~ A marker counts only where it is being used as a marker. A span has to open at a word boundary and close at one, so .. code-block:: none _this_ and *that* are emphasis simul_historical_data is a name, left alone 2*x*3 is arithmetic, left alone which is what lets the underscore be used at all in a toolbox whose option names are full of them. Where prose stops and code begins ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Within a section the **first** run of full-line comments is prose. Every comment after the first line of code belongs to the listing. That is the rule cell mode follows, and it is worth following: the alternative surprises people, because a comment written to explain the next three lines of code would silently leave the listing and reappear as a paragraph somewhere above it. Cross references ----------------- A heading or a display equation can carry a label, and anything else in the document can point at it: .. code-block:: matlab %% What the steady state says {#steady} % Capital per unit of labour follows from the discount factor: % % $$ \frac{Y}{K} = \left( \frac{1/\beta - 1 + \delta}{\alpha} % \right)^{\frac{1}{1-\psi}} $$ {#capital} and later, anywhere: .. code-block:: matlab % The levels asked for are deviations from the steady state of % [#steady], the one that [#capital] pins down. which comes out as "deviations from the steady state of section 4, the one that Equation 1 pins down", with both as clickable links. References are coloured, in a restrained blue, because one set in the same black as the sentence around it reads as ordinary text and nobody tries it. ``ColorLinks`` set to false turns the colour off for a document going to a monochrome printer; the links still work. ``LinkColor`` takes any xcolor name. The author never writes the number. Insert a section above and every reference to what follows renumbers itself, which is the whole reason for labelling rather than typing "see section 4". A labelled equation is numbered. A reference to an unnumbered equation has nothing to point at, so labelling one numbers it. The reference names the kind of thing as well as its number, so you write ``[#steady]`` and not "section [#steady]". To *show* the syntax rather than use it, put it in backticks: ``` `[#name]` ``` is printed as an example and not resolved. Margin bookmarks ----------------- Every listing carries a note in the margin giving the span of the source file it came from: .. code-block:: none lines 24--36 The document and the script are the same file, and the bookmark is what makes that usable: read a paragraph, look at the margin, open the editor at that line. Numbering the listing lines against the source, which ``NumberLines`` does, gives the same link inside the listing; the bookmark gives it at a glance without reading the listing at all. Turn it off with ``MarginLines`` set to false. It is on by default and it widens the right margin to make room, because a note squeezed into a narrow margin wraps and looks like damage. Figures -------- Every figure a block creates is placed where it was created, in creation order. A figure the block merely updated is left alone, because it was already shown where it was first drawn. A figure is captioned with its own title: .. code-block:: matlab figure; plot(t, y); title('An unanticipated ten percent fall in efficiency'); An author who wrote ``title`` has already said what the figure is, and being asked to say it again in separate markup would be being asked twice for the same sentence. A figure with several axes is a panel, so the first title would describe only one piece of it and no caption is invented. The figure's ``Name`` is the fallback. Options -------- Execution ~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 26 20 54 * - Option - Default - Meaning * - ``EvalCode`` - ``true`` - run the code and capture what it produced * - ``OnError`` - ``"report"`` - ``"report"`` puts the failure in the document and carries on; ``"continue"`` runs on silently; ``"stop"`` rethrows * - ``ShowCode`` - ``true`` - include the listings * - ``ShowOutput`` - ``true`` - include what the code printed * - ``MaxOutputLines`` - ``40`` - longer output is cut, and the cut is stated rather than hidden * - ``NumberLines`` - ``true`` - number listings against the source file's own line numbers * - ``MarginLines`` - ``true`` - a margin bookmark beside each listing giving its span in the source file Content ~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 26 20 54 * - Option - Default - Meaning * - ``Title``, ``Author``, ``Abstract`` - from the script - taken from the first section when not given * - ``Toc`` - ``true`` - a table of contents * - ``TitlePage`` - ``true`` - with ``false`` the document starts at the first heading * - ``Stamp`` - ``true`` - record RISE version, MATLAB version, date and run time ``TitlePage`` is what a note, a memo, or a piece destined for a larger document wants. The title is still used for the running head and the file name, the abstract still appears, and the first section stays in the body rather than being consumed as the document title. The page ~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 26 20 54 * - Option - Default - Meaning * - ``DocumentClass`` - ``"article"`` - also ``report``, ``book``, ``letter``, ``proc``, ``minimal`` * - ``Orientation`` - ``"portrait"`` - ``landscape`` suits a report of wide figures or wide tables * - ``PaperSize`` - ``"letterpaper"`` - also ``a4paper``, ``legalpaper`` * - ``PointSize`` - ``"11pt"`` - also ``10pt``, ``12pt`` * - ``Margins`` - see below - struct with ``Top``, ``Bottom``, ``Left``, ``Right`` in centimetres Margins default to 2, 3.5, 2 and 2 centimetres, with the right margin widened to 3.6 when margin bookmarks are on. Setting ``Margins`` overrides that, bookmarks or not, so leave it alone unless you mean it. .. code-block:: matlab rise.publish('wide_report.m', 'Orientation', "landscape", ... 'PaperSize', "a4paper") Output ~~~~~~~ .. list-table:: :header-rows: 1 :widths: 26 20 54 * - Option - Default - Meaning * - ``SaveAs`` - the script's name - output file name * - ``FigureFormat`` - ``"pdf"`` - ``"pdf"`` for vector figures, ``"png"`` for raster * - ``FigureWidth`` - ``0.85`` - as a fraction of the text width * - ``Resolution`` - ``200`` - dots per inch, for ``"png"`` * - ``KeepTempFiles`` - ``false`` - keep the working directory, including the generated LaTeX What it guarantees ------------------- **The source file is never modified.** Everything happens in a temporary working directory. **The script runs with the working directory set to its own folder**, so a relative load behaves exactly as it does when the file is run by hand. **All the code blocks share one workspace**, so a variable assigned in one block is available in the next, exactly as in the editor. **A failing block does not lose the document.** Under the default, ``OnError`` of ``"report"``, the failure is typeset where it happened and the rest of the script still runs. Use ``"stop"`` when a failure should be treated as a broken build. **The document says how it was made.** The stamp records the RISE version, the MATLAB version, the date and the total run time, so two documents can be compared knowing whether they were produced the same way. Publishing without running --------------------------- .. code-block:: matlab rise.publish('walkthrough.m', 'EvalCode', false) The script is typeset but not executed. Useful for a document whose code is slow, needs data that is not present, or is deliberately illustrative. A worked example ----------------- ``rise-modern-tutorials/Reporting/mfile_publisher`` builds a small real business cycle model, solves it, runs a deterministic experiment and publishes the result twice, once with a title page and once without. .. seealso:: :doc:`Reporting system`, :doc:`rnotes_reporting`